fix: expose entitlement guard contract metadata - #1027

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/entitlements-core/src/libs/decorators/RequireEntitlement.ts`:
- Around line 20-26: The issue is that on line 25 in the
appendEntitlementRequirement call with propertyKey, using target.constructor is
incorrect for static methods because target is already the constructor function
for static methods, making target.constructor === Function which causes metadata
to be recorded on Function instead of the actual class. To fix this, determine
whether the property is a static method or instance method and pass the correct
target: use target directly for static methods (where target is the constructor
function) and target.constructor for instance methods (where target is the
prototype). You can distinguish between static and instance methods by checking
if target is a constructor function versus a prototype object.

In `@packages/entitlements-core/src/libs/EntitlementGuard.ts`:
- Around line 217-230: The recordEntitlementGuard call on the
EntitlementAuditSink is being directly awaited, which means failures in the
audit sink can cause exceptions that override the guard result and turn allowed
requests into errors. Wrap the await call in a try-catch block so that audit
sink failures are caught and logged separately via telemetry without affecting
the original guard result. The guard should still return its decision regardless
of whether the audit sink succeeds or fails, ensuring that audit failures don't
break the entitlement check flow. Apply this isolation pattern to all
recordEntitlementGuard calls in the file including the ones referenced in the
"Also applies to" section.
- Around line 80-90: The telemetry is currently recording `problem.detail ??
problem.message` as the reason code in the span, which can contain sensitive
information like tenant identifiers or arbitrary custom strings, creating
high-cardinality telemetry. In the recordDenied method calls within the
EntitlementGuard class (at the indicated line ranges including around line
80-90, 239-241, and 310), replace the fourth parameter that passes
`problem.detail ?? problem.message` with stable reason code values instead, such
as using `result.reason ?? "not_entitled"` or constant values like
`"provider_unavailable"` to ensure only predictable, low-cardinality codes are
recorded for telemetry.
- Line 6: The import statement in EntitlementGuard.ts is mixing a value import
(getEntitlementRequirements) with an inline type import (type
EntitlementRequirement) in a single import statement. According to the
repository's TypeScript guidelines, type imports must use the separate import
type syntax. Split the import statement into two separate imports from the same
module: one regular import statement for the value getEntitlementRequirements
and one import type statement for the EntitlementRequirement type.

In `@packages/entitlements-core/src/libs/EntitlementRequirement.ts`:
- Around line 121-129: The isEntitlementRequirement function currently only
validates the feature field but does not validate the resource field structure.
This can allow invalid resource objects (where type or other properties may not
be strings) to pass through to defineEntitlementRequirement, causing runtime
TypeErrors when accessing .length on lines 144, 150, and 156. Enhance the
validation in isEntitlementRequirement to also check that the resource field
exists and has a valid shape with all required string properties (such as type)
before returning true, ensuring that only properly structured
EntitlementRequirement objects pass validation and preventing downstream errors
in the resource field access.

In `@packages/protocols-core/src/libs/ContractGraphDiff.ts`:
- Around line 179-215: The function diffEntitlementRequirements has a bug where
duplicate changes are generated when entitlements with the same fingerprint
appear multiple times in the arrays. The issue is that while the function
creates Sets for membership checking (baselineEntitlements and
currentEntitlements), it then iterates over the original arrays
(current.entitlements and baseline.entitlements) which may contain duplicates.
This causes the same change to be added multiple times to the changes array. To
fix this, instead of iterating directly over current.entitlements and
baseline.entitlements, create deduplicated collections of entitlements by their
fingerprints and iterate over those deduplicated collections instead, ensuring
each unique entitlement fingerprint is only processed once.

In `@packages/protocols-core/src/tests/helpers/test-decorators.ts`:
- Around line 97-113: The RequiresEntitlement decorator currently overwrites
existing entitlement requirements instead of accumulating them when applied
multiple times to the same target. To fix this, retrieve any existing metadata
using Reflect.getMetadata with the same ENTITLEMENT_REQUIREMENTS_KEY,
propertyKey, and target before calling Reflect.defineMetadata in both the method
decorator case (when propertyKey is provided) and the class decorator case (when
it is not). If existing metadata is found, append the new requirement to that
array before defining the metadata; otherwise, create a new array with just the
current requirement. This ensures that multiple decorator applications
accumulate requirements rather than replacing them.

In `@public-api-surface.snapshot.json`:
- Around line 3423-3430: The entries for ENTITLEMENT_REQUIRED_KEY and
ENTITLEMENT_REQUIREMENTS_KEY in the snapshot file are missing the
declarationKind field that all other const exports contain. Add
"declarationKind": "const" to both of these entries to match the structure of
other const declarations in the snapshot and ensure API validation tools can
properly categorize these exports.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/entitlements-core/src/libs/EntitlementGuard.ts`:
- Around line 71-95: The createGuardInput method call at line 72 is executed
outside the try-catch block, which means any EntitlementDeniedProblem thrown
during input validation and preprocessing bypasses the recordDenied call that is
inside the catch block. This results in missing denied telemetry and audit logs.
Move the createGuardInput call inside the try block (before the
entitlementManager.check call) so that exceptions thrown during input creation
are also caught and properly recorded through the recordDenied method.